introduction of x-maintained field

Once merged, I plan to publish a discuss post (that will hopefully clarify some bits) -- suggestions / comments welcome:

x-maintenance-intent

We've had some further discussions on Phase 3 and the semantics of the
x-maintenance-intent field.

Goal

Our aim is to be not disruptive for the common OCaml programmer or user. The
opam-repository supports (from February 1st on) OCaml 4.08 and greater. This
means that if you install OCaml 4.08 you should be able to install all the
packages that have ever been released with 4.08 support.

This means the revised semantics of "(latest)" is "the latest version of this
package, so that every supported OCaml version will have an installation
candidate".

Example

Let me give you an example, consider the package "basic" which exists in three
versions:
basic.1.0.0 with the dependency "ocaml" {>= "4.05" & < "5"}
basic.1.0.1 with the dependency "ocaml" {>= "4.08" & < "5"}
basic.2.0.0 with the dependency "ocaml" {>= "4.14" & < "5"}

Here, if the x-maintenance-intent: [ "(latest)" ] is present, we will only
(try to) archive basic.1.0.0 -- since 1.0.1 is needed for OCaml 4.08 .. 4.13.
I hope this is clear.

Default value

The default value of x-maintenance-intent will for now be "(any)" - so all
versions are kept. In the future, we may change this default to "(latest)",
but will announce this ahead of the change with plenty of time.

This default value is agreed on by the non-disruptive agreement to cause the
least trouble.

x-maintained

In addition to the x-maintenance-intent - which covers the semantics of all
versions of an opam package, we support another field, x-maintained: BOOL.
This is an overwrite for a specific opam package version, and allows to declare
whether it is maintained or not.

It is useful in the setting where you've lots of pre-releases that are no
longer maintained and you like to state this without writing a global intent
for the opam package (e.g. for the OCaml compiler packages, the alpha, beta, and
rc versions). Here, x-maintained: false is a nice setting. NB: earlier we
proposed flags: deprecated - but we stay away from the flags, since there may
be packages that are deprecated but still maintained (opam prints a warning if
you install a package with the deprecated flag).

If you have a private project and depend on a specific version of an opam
package, you can as well PR the x-maintained: true field for that opam file
(please specify when, who, and why). This will ensure that this opam file stays
in the opam repository.

Phase 3

In Phase 3, we will consider all packages marked with x-maintenance-intent
(the versions not matching the intent) and x-maintained: false to be archived.

We plan to ensure that (a) all supported OCaml versions will retain an
installation candidate (b) all reverse dependencies will still be installable.
As a note, if you have an availability condition (some version will only work
on some OS), we won't take that into consideration -- you will need to specify
the x-maintenance-intent to cover your versions.

Our plan is to publish the list of packages to be archived by February 15th
on this discourse. It is likely we'll have candidate lists PRed to the
opam-repository-archive
earlier. We have lots of ideas and plans for CI systems to give feedback which
opam versions are falling into the maintenance intent when you open a PR to
the opam-repository (but we're not there yet).

Future

As noted above, the default value of x-maintenance-intent may change in time.
If this is decided, we will announce this with plenty of time before.

Also, at some point in the future we will bump the OCaml lower bound (from
February 1st it is 4.08).

Action

For the smooth shrinking of the opam-repository, please don't hesitate to fill
in your x-maintenance-intent (especially "(none)" and "(latest)" are fine
and safe choices).

If you want to contribute more, the opam-repository needs help for triaging and
merging PRs - why not become a maintainer? See the old but still valid
'call for new opam-repository maintainers'
if you're interested.